home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbsqlexec.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.0 KB  |  83 lines
  1. .Na "dbsqlexec" 
  2. .Aa
  3. .Fu
  4. Send a command batch to \*S.
  5. .Ih "command batch, executing"
  6. .Ih "command batch, sending to \*S"
  7. .Sy
  8. .Sf "RETCODE dbsqlexec(dbproc)"
  9. .Sp "DBPROCESS" "*dbproc"
  10. .Co
  11. .Bl
  12. This routine sends SQL commands,
  13. stored in the command buffer of the DBPROCESS,
  14. to \*S.
  15. Commands may be added to the DBPROCESS structure by calling
  16. \f2dbcmd()\f1 or \f2dbfcmd()\f1.
  17. .Bl
  18. Once
  19. .I "dbsqlexec()"
  20. returns SUCCEED,
  21. the application must call
  22. .I "dbresults()"
  23. to process the results.
  24. .Bl
  25. The typical sequence of calls is:
  26. .ta +4n +4n +4n +4n +4n +4n
  27. .SD
  28. .so dbsqlexec.ex
  29. .ED
  30. .Bl
  31. \f2dbsqlexec()\f1 is equivalent to \f2dbsqlsend()\f1 followed by \f2dbsqlok()\f1.
  32. However, after sending a query to \*S, \f2dbsqlexec()\f1 waits until
  33. a response is received or until the timeout period has elapsed.
  34. By substituting \f2dbsqlsend()\f1 and \f2dbsqlok()\f1 for \f2dbsqlexec()\f1,
  35. you can sometimes provide a way for the application
  36. to respond more effectively to multiple input and output streams.
  37. See the manual pages for those two routines for more information.
  38. .Bl
  39. An asynchronous version of \f2dbsqlexec()\f1, called \f2dbsqlexec_a()\f1, is available for VMS.
  40. .Bz
  41. .Pa
  42. .Pi dbproc
  43. A pointer to the DBPROCESS structure that provides the connection
  44. for a particular front-end/\*S process.  It contains all the
  45. information that \*L uses to manage communications and data between the
  46. front end and \*S.
  47. .in -.375i
  48. .Re
  49. .br
  50. SUCCEED or FAIL.
  51. The most common reason for failing is a SQL syntax error.
  52. \f2dbsqlexec()\f1 will also fail if there are semantic errors, such as
  53. incorrect column or table names.
  54. Failure occurs if \f2any\f1 of the commands in the batch contains a semantic or syntax error.
  55. \f2dbsqlexec()\f1 also fails if previous results had not been processed, or if
  56. the command buffer was empty.
  57. .sp 0.5v
  58. In addition, a run-time error, such as a database protection violation, will cause \f2dbsqlexec()\f1 to
  59. fail \f2if\f1 the command buffer contains only a single command.
  60. If the command buffer contains multiple commands, a run-time error will \f2not\f1 cause \f2dbsqlexec()\f1 to fail.
  61. Instead, failure will occur with the \f2dbresults()\f1 call that processes the command causing the run-time error.
  62. .sp 0.5v
  63. The situation is a bit more complicated for run-time errors and stored procedures.
  64. A run-time error on an EXECUTE command may cause \f2dbsqlexec()\f1 to fail,
  65. in accordance with the rule given in the previous paragraph.
  66. A run-time error on a statement \f2inside\f1 a stored procedure will not cause \f2dbsqlexec()\f1 to fail,
  67. however.
  68. For example, if the stored procedure contains an INSERT statement and the user does not have
  69. insert permission on the database table, the INSERT statement will fail, but \f2dbsqlexec()\f1
  70. will still return SUCCEED.
  71. To check for run-time errors inside stored procedures, use the \f2dbretstatus()\f1 routine
  72. to look at the procedure's return status, and trap relevant \*S messages inside your message handler.
  73. .Sa
  74. dbcmd,
  75. dbfcmd,
  76. dbnextrow,
  77. dbresults,
  78. dbretstatus,
  79. dbsettime,
  80. dbsqlexec_a,
  81. dbsqlok,
  82. dbsqlsend
  83.